Artemis Trouble Ticket API

This section defines the key fields used in the TMF621 Trouble Ticket API. Attributes listed here may appear in request or response payloads depending on the operation. Fields are derived from TMF621 v5.0.0 and follow TMF630 REST design principles.

API request payload

POST /troubleTicket

Section	Field Name	Example Field Value	Description
HTTP Header Name	Correlation-ID	c97ded75-44fa-4b69-9f3b-01d513a41efe	A GUID to relate requests belonging to the same transaction
Payload First Class Attribute	description	No dial tone on customer line	A String. Description of the trouble or issue. Mandatory.
Payload First Class Attribute	name	Voice QOS, faint calls	A short description provided by the user that create the ticket
Payload First Class Attribute	ticketType	fault	Indicates category of issue. To be set to fault. Mandatory.
Payload First Class Attribute	severity	High	The severity of the issue, as per partners' definition. Mandatory.
Payload First Class Attribute	dateFirstFound	2025-01-02T09:00:00Z	Mandatory. Represents when the fault occurred for the first time.
Payload First Class Attribute	twentyFourHourAccess	true	Mandatory. Defines whether the EU will be available 24 hour in the event an appointment is required.
Payload First Class Attribute	earliestNextAccessDateTime	2025-01-02T09:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	latestAccessDateTime	2025-01-01T17:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	troubleTicketCharacteristic	See troubleTicketCharacteristic table	An array of Characteristic objects, defined by TMF pattern.
Payload First Class Attribute	attachment	See attachment table	An array of AttachmentRefOrValue. Optional file evidence; 1 allowed per submission.
Payload First Class Attribute	note	See note table	Array of Note objects (inline). Free-text notes from partners, suppliers, end users and PXC agents.
Payload First Class Attribute	relatedEntity	See relatedEntity table	References the product, service, or billing account affected by the fault.
Payload First Class Object	troubleTicketSpecification	See troubleTicketSpecification table	A reference to a predefined classification of the trouble ticket.
Payload First Class Attribute	relatedParty	See relatedParty table	Identifies the people or organizations involved with the ticket.
Payload First Class Attribute	troubleTicketRelationship	See troubleTicketRelationship table	Relates the current trouble ticket to other tickets (e.g., parent, duplicateOf).
Payload First Class Attribute	externalIdentifier	See externalIdentifier table	Partner reference ID, mapped to TMF621 externalIdentifier array.
Payload First Class Object	appointment	See appointment table	Reference to TMF646 appointment (id, href, description).
TMF metadata	@type	PartnerTroubleTicket	Subclass indicator for TroubleTicket extension. Mandatory.
TMF metadata	@baseType	TroubleTicket	Core resource type. Mandatory.
TMF metadata	@schemaLocation	https://.../schema/PartnerTroubleTicket.json	Defines schema for extended attributes.

Example:

{
   "description":"Voice QOS, unable to authenticate issue reported by customer. Customer reports bad service when calling.",
   "name":"Voice QOS, faint calls",
   "ticketType":"Fault",
   "severity":"High",
   "dateFirstFound":"2025-02-25T00:00:00Z",
   "twentyFourHourAccess":true,
   "troubleTicketCharacteristic":[
      {
         "name":"faultType",
         "value":"Faint calls",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"frequency",
         "value":"Intermittent",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"examplesWhenFaultOccurs",
         "value":"Every Tuesday evening at 9 PM",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"allCPEChecksComplete",
         "value":true,
         "valueType":"boolean",
         "@type":"BooleanCharacteristic"
      },
      {
         "name":"numberDialled",
         "value":"016-1234-567-89",
         "valueType":"string",
         "@type":"StringCharacteristic"
      },
      {
         "name":"authorizeEngineerEffort",
         "value":false,
         "valueType":"boolean",
         "@type":"BooleanCharacteristic"
      },
      {
         "name":"safetyNote",
         "text":"Beware the dog in the front garden",
         "valueType":"string",
         "@type":"StringCharacteristic"
      }
   ],
   "attachment":[
      {
         "description":"Speed test screenshot attached for more information.",
         "attachmentType":"screenshot",
         "mimeType":"image/png",
         "name":"Speed_test_image",
         "content":"iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAIAAAD7GkWBAA",
         "@type":"Attachment"
      }
   ],
   "note":[
      {
         "text":"This is very urgent, please sort this out as soon as possible",
         "author":"Jane Smith",
         "source":"endUser",
         "@type":"PartnerNote",
         "@baseType":"Note"
      }
   ],
   "relatedEntity":[
      {
         "role":"affectedEntity",
         "@type":"RelatedEntity",
         "entity":{
            "id":"SOGEA777",
            "@type":"EntityRef",
            "@referredType":"Service"
         }
      },
      {
         "role":"relatedAccount",
         "@type":"RelatedEntity",
         "entity":{
            "id":"XX788956566",
            "@type":"EntityRef",
            "@referredType":"BillingAccount"
         }
      }
   ],
   "troubleTicketSpecification":{
      "id":"Voice-QOS",
      "@type":"TroubleTicketSpecificationRef"
   },
   "relatedParty":[
      {
         "role":"reportingParty",
         "partyOrPartyRole":{
            "@type":"Organization",
            "@baseType":"Party",
            "tradingName":"<CompanyName>",
            "contactMedium":[
               {
                  "contactType":"primary",
                  "phoneNumber":"+4412345",
                  "@type":"PhoneContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"primary",
                  "emailAddress":"john.doe@<example>.com",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"secondary",
                  "emailAddress":"support@<example>.co.uk",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               }
            ]
         },
         "@type":"RelatedPartyOrPartyRole"
      },
      {
         "role":"endUser",
         "partyOrPartyRole":{
            "@type":"Individual",
            "@baseType":"Party",
            "givenName":"Jane",
            "familyName":"Smith",
            "contactMedium":[
               {
                  "contactType":"primary",
                  "phoneNumber":"+449876543210",
                  "@type":"PhoneContactMedium",
                  "@baseType":"ContactMedium"
               },
               {
                  "contactType":"primary",
                  "emailAddress":"Jane.smith@<example>.com",
                  "@type":"EmailContactMedium",
                  "@baseType":"ContactMedium"
               }
            ]
         },
         "@type":"RelatedPartyOrPartyRole"
      }
   ],
   "externalIdentifier":[
      {
         "id":"PART123456",
         "owner":"<PartnerOwnerName>",
         "externalIdentifierType":"partnerRef",
         "@type":"ExternalIdentifier"
      }
   ],
   "appointment":{
      "id":"APP67789",
      "@type":"AppointmentRef"
   },
   "@type":"PartnerTroubleTicket",
   "@baseType":"TroubleTicket"
}

Response Shaping (fields parameter)

The TMF standard defines a fields query parameter to allow clients to limit which fields are included in API responses. However, this parameter is currently not fully supported in the implementation of the Trouble Ticket API.

• Any use of fields in the request of POST /troubleTicket will be ignored.
• A default list of attributes will be returned in the response, with href to get the full ticket, if required.